\chapter{Message library}

The following functions are used to access the different fields of a message, even in a user program. We use such functions because it makes maintainance easier as it abstracts the internal structure of a message which can then change without affecting anything else. Those functions are NOT accessed through a syscall by the user programs because they act on a piece of memory owned by the process (the message). Just like the functions in string.h, they form an abstraction layer that makes life easier for the programmer (and the system designer who can change the type message without worrying about breaking old programs as long as he keeps those functions up to date).\\

From a user program's point of view, those functions are a part of the API. One can then see them as forming a user-level library.\\

The functions below share the same parameter, called target, which is of type \textit{message\_t}, the type used to represent a message in a user program. In the following, the message pointed by target is simply referenced as \textit{the message}. Furthermore, they also share the same return value in the case of a function being called with a NULL pointer or if the data flag does not correspond, return value which is INCORRECT\_REQUEST.\\

The following examples assumes that m is a variable of type \textit{message\_t} which has been used to receive a message before (so, it is not NULL).

\section{message\_get\_from}

\texttt{int32\_t message\_get\_from(message\_t target)}

\subsection*{Description}
This will return the sender of the message. 
\subsection*{Examples}
 \begin{lstlisting}
    if(message_get_from(m) == some_pid)
        ecrire("The correct sender has been found!");
      }
 \end{lstlisting}

\section{message\_get\_to}

\texttt{int32\_t message\_get\_to(message\_t target)}

\subsection*{Description}
This will return the recipient of the message. It is therefore another way to do a obtenir\_pid() with a message ! 

\section{message\_get\_priority}

\texttt{int32\_t message\_get\_priority(message* target)}

\subsection*{Description}
This will return the priority of the message. 
\subsection*{Examples}
 \begin{lstlisting}
   if(message_get_priority(m) == priority{
   	//do some computation   
	}

 \end{lstlisting}

\section{message\_get\_data\_flag}

\texttt{int8\_t message\_get\_data\_flag(message\_t target)}

\section*{Description}
Returns the data flag of this message. It is needed for the applications that use several types of messages. The return values, besides INCORRECT\_REQUEST, are:
\begin{itemize}
	\item INT\_DATA if the message carries an integet
	\item STR\_DATA if the message carries a string
	\item PINFO\_DATA if the message carries information about the sender process
\end{itemize}
\subsection*{Examples}
 \begin{lstlisting}
 		switch(message_get_data_flag(m)){
		case INT_DATA:
			...
		case STR_DATA:
			...
		case PINFO_DATA:
			...
		}
 \end{lstlisting}

\section{message\_get\_int\_value}

\texttt{int32\_t message\_get\_int\_value(messages\_t target)}

\section*{Description}
Returns the integer stored in the message if the data flag is set to INT\_DATA or 0 otherwise
\subsection*{Examples}
 \begin{lstlisting}
 	int value = message_get_int_value(m)
 \end{lstlisting}

\section{message\_get\_str\_value}

\texttt{char* message\_get\_str\_value(message\_t target)}

\subsection*{Description}
Returns a pointer to the string stored in target if the data flag is set to STR\_DATA or NULL otherwise.  
\subsection*{Examples}
 \begin{lstlisting}
 	char* string = message_get_str_value(m);
	if(string != NULL)
   ecrire(string);
 \end{lstlisting}

\section{message\_get\_pinfo\_*\_value}

\texttt{int32\_t message\_get\_pinfo\_priority\_value(message\_t target)}\\
\texttt{int32\_t message\_get\_pinfo\_program\_id\_value(message\_t target)}\\
\texttt{int32\_t message\_get\_pinfo\_parent\_value(message\_t target)}\\
\texttt{int32\_t message\_get\_pinfo\_status\_value(message\_t target)}\\

The message\_get\_pinfo\_*\_value functions are used to access the data included in a message carrying data of type process information. Those information apply to the sender.\\

The available functions are:
\begin{itemize}
	\item message\_get\_pinfo\_priority\_value which returns the priority the sender has when it was sending this message
	\item message\_get\_pinfo\_program\_id\_value which returns the program executed by the sender at the time of sending
	\item message\_get\_pinfo\_status\_value which returns the status of the sender. The status is the value given as parameter to the functions tuer and quitter. This field isonly significant in a supervision message
	\item message\_get\_pinfo\_parent\_value which returns the parent of the process at the moment the message was sent
\end{itemize}


